Add all docs in-tree
authorAlex Crichton <alex@alexcrichton.com>
Thu, 21 Aug 2014 16:54:53 +0000 (09:54 -0700)
committerAlex Crichton <alex@alexcrichton.com>
Thu, 21 Aug 2014 17:12:35 +0000 (10:12 -0700)
24 files changed:
.gitignore
.travis.install.deps.sh
.travis.yml
src/doc/Gemfile [new file with mode: 0644]
src/doc/Gemfile.lock [new file with mode: 0644]
src/doc/config.rb [new file with mode: 0644]
src/doc/mkfonts.rb [new file with mode: 0644]
src/doc/source/CNAME [new file with mode: 0644]
src/doc/source/faq.md [new file with mode: 0644]
src/doc/source/guide.md [new file with mode: 0644]
src/doc/source/images/Cargo-Logo-Small.png [new file with mode: 0644]
src/doc/source/images/forkme.png [new file with mode: 0644]
src/doc/source/images/noise.png [new file with mode: 0644]
src/doc/source/index.md [new file with mode: 0644]
src/doc/source/javascripts/all.js [new file with mode: 0644]
src/doc/source/layouts/layout.erb [new file with mode: 0644]
src/doc/source/manifest.md [new file with mode: 0644]
src/doc/source/native-build.md [new file with mode: 0644]
src/doc/source/stylesheets/all.css.scss [new file with mode: 0644]
src/doc/source/stylesheets/colors.css.scss [new file with mode: 0644]
src/doc/source/stylesheets/fonts.css.scss [new file with mode: 0644]
src/doc/source/stylesheets/normalize.css [new file with mode: 0644]
src/doc/source/stylesheets/solarized.css.scss [new file with mode: 0644]
src/doc/woffify.rb [new file with mode: 0644]

index 48164142ec20b7f0476f8572a310969f2af744af..ca38a825f464407af7aad3836ffa4b8bd5efc40b 100644 (file)
@@ -3,3 +3,4 @@
 /config.stamp
 /Makefile
 /config.mk
+src/doc/build
index eee1850d4eed10a03eb5639383146d32ae58c21e..54bffc80b7c6ffaf31b7175db299c264144275ab 100755 (executable)
@@ -2,7 +2,8 @@ set -x
 
 if [ "${TRAVIS_OS_NAME}" = "osx" ] || [ "${PLATFORM}" = "mac" ]; then
     target=apple-darwin
-elif [ "${TRAVIS_OS_NAME}" = "linux" ] || [ "${PLATFORM}" = "linux" ]; then
+elif [ "${TRAVIS_OS_NAME}" = "linux" ] || [ "${PLATFORM}" = "linux" ] ||
+     [ "${TRAVIS_OS_NAME}" = "" ]; then
     target=unknown-linux-gnu
 elif [ "${OS}" = "Windows_NT" ] || [ "${PLATFORM}" = "win" ]; then
     target=pc-mingw32
index b897f3577773ca3cbfc248579c4e1c4c93cfca2b..f1ee1cbd95f9abb293c2a874c79fb45f594593f9 100644 (file)
@@ -1,18 +1,29 @@
 language: rust
-
 install:
   - sh ./.travis.install.deps.sh
-
 script:
   - ./configure --local-rust-root=`pwd`/rustc
   - make
   - make test
   - make distcheck
-
+after_success: |
+  [ $TRAVIS_BRANCH = master ] &&
+  [ $TRAVIS_PULL_REQUEST = false ] &&
+  [ $BITS = 64 ] &&
+  [ $(uname -s) = Linux ] &&
+  (cd src/doc &&
+   bundle &&
+   bundle exec middleman build) &&
+  echo crates.io >> src/doc/build/CNAME &&
+  sudo pip install ghp-import
+  ghp-import -n src/doc/build &&
+  git push -f https://${TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git gh-pages
 env:
-  - BITS=32
-  - BITS=64
-
+  matrix:
+    - BITS=32
+    - BITS=64
+  global:
+    secure: fV37lqpHoVgHJHBdPegut8uf5sfaK/SrLx+Npn1ngPPzUuIh+BZkgqX11FdAxIu05YfI/C/M3smG5SOxb5X0ojK8VQdRtvb8KM6b2G839jegxGk2Bs+bAWMFVrJDl5JCZec+zU/rPlZPXLLnOv23ReGv9UvwgxLw1AJjZ2WkJ5M=
 os:
   - linux
   - osx
diff --git a/src/doc/Gemfile b/src/doc/Gemfile
new file mode 100644 (file)
index 0000000..afd0d1a
--- /dev/null
@@ -0,0 +1,18 @@
+# If you have OpenSSL installed, we recommend updating
+# the following line to use "https"
+source 'http://rubygems.org'
+
+gem "middleman", "~>3.3.3"
+gem "middleman-blog"
+
+gem "middleman-syntax"
+gem "redcarpet"
+
+# Live-reloading plugin
+gem "middleman-livereload", "~> 3.1.0"
+
+# For faster file watcher updates on Windows:
+gem "wdm", "~> 0.1.0", :platforms => [:mswin, :mingw]
+
+# Windows does not come with time zone data
+gem "tzinfo-data", platforms: [:mswin, :mingw]
diff --git a/src/doc/Gemfile.lock b/src/doc/Gemfile.lock
new file mode 100644 (file)
index 0000000..4ba15d2
--- /dev/null
@@ -0,0 +1,134 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (4.1.1)
+      i18n (~> 0.6, >= 0.6.9)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.1)
+      tzinfo (~> 1.1)
+    addressable (2.3.6)
+    chunky_png (1.3.1)
+    coffee-script (2.2.0)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.7.0)
+    compass (0.12.6)
+      chunky_png (~> 1.2)
+      fssm (>= 0.2.7)
+      sass (~> 3.2.19)
+    compass-import-once (1.0.4)
+      sass (>= 3.2, < 3.5)
+    em-websocket (0.5.1)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0.6.0)
+    erubis (2.7.0)
+    eventmachine (1.0.3)
+    execjs (2.2.0)
+    ffi (1.9.3)
+    fssm (0.2.10)
+    haml (4.0.5)
+      tilt
+    hike (1.2.3)
+    hooks (0.4.0)
+      uber (~> 0.0.4)
+    http_parser.rb (0.6.0)
+    i18n (0.6.9)
+    json (1.8.1)
+    kramdown (1.4.0)
+    listen (1.3.1)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+      rb-kqueue (>= 0.2)
+    middleman (3.3.3)
+      coffee-script (~> 2.2.0)
+      compass (>= 0.12.4)
+      compass-import-once (= 1.0.4)
+      execjs (~> 2.0)
+      haml (>= 4.0.5)
+      kramdown (~> 1.2)
+      middleman-core (= 3.3.3)
+      middleman-sprockets (>= 3.1.2)
+      sass (>= 3.2.17, < 4.0)
+      uglifier (~> 2.5)
+    middleman-blog (3.5.3)
+      addressable (~> 2.3.5)
+      middleman-core (~> 3.2)
+      tzinfo (>= 0.3.0)
+    middleman-core (3.3.3)
+      activesupport (~> 4.1.0)
+      bundler (~> 1.1)
+      erubis
+      hooks (~> 0.3)
+      i18n (~> 0.6.9)
+      listen (~> 1.1)
+      padrino-helpers (~> 0.12.1)
+      rack (>= 1.4.5, < 2.0)
+      rack-test (~> 0.6.2)
+      thor (>= 0.15.2, < 2.0)
+      tilt (~> 1.4.1, < 2.0)
+    middleman-livereload (3.1.1)
+      em-websocket (>= 0.2.0)
+      middleman-core (>= 3.0.2)
+      multi_json (~> 1.0)
+      rack-livereload
+    middleman-sprockets (3.3.3)
+      middleman-core (>= 3.2)
+      sprockets (~> 2.2)
+      sprockets-helpers (~> 1.1.0)
+      sprockets-sass (~> 1.1.0)
+    middleman-syntax (2.0.0)
+      middleman-core (~> 3.2)
+      rouge (~> 1.0)
+    minitest (5.3.5)
+    multi_json (1.10.1)
+    padrino-helpers (0.12.2)
+      i18n (~> 0.6, >= 0.6.7)
+      padrino-support (= 0.12.2)
+      tilt (~> 1.4.1)
+    padrino-support (0.12.2)
+      activesupport (>= 3.1)
+    rack (1.5.2)
+    rack-livereload (0.3.15)
+      rack
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rb-fsevent (0.9.4)
+    rb-inotify (0.9.5)
+      ffi (>= 0.5.0)
+    rb-kqueue (0.2.3)
+      ffi (>= 0.5.0)
+    redcarpet (2.3.0)
+    rouge (1.4.0)
+    sass (3.2.19)
+    sprockets (2.12.1)
+      hike (~> 1.2)
+      multi_json (~> 1.0)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sprockets-helpers (1.1.0)
+      sprockets (~> 2.0)
+    sprockets-sass (1.1.0)
+      sprockets (~> 2.0)
+      tilt (~> 1.1)
+    thor (0.19.1)
+    thread_safe (0.3.4)
+    tilt (1.4.1)
+    tzinfo (1.2.1)
+      thread_safe (~> 0.1)
+    uber (0.0.6)
+    uglifier (2.5.1)
+      execjs (>= 0.3.0)
+      json (>= 1.8.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  middleman (~> 3.3.3)
+  middleman-blog
+  middleman-livereload (~> 3.1.0)
+  middleman-syntax
+  redcarpet
+  tzinfo-data
+  wdm (~> 0.1.0)
diff --git a/src/doc/config.rb b/src/doc/config.rb
new file mode 100644 (file)
index 0000000..fe4d7f2
--- /dev/null
@@ -0,0 +1,83 @@
+###
+# Compass
+###
+
+# Change Compass configuration
+# compass_config do |config|
+#   config.output_style = :compact
+# end
+
+###
+# Page options, layouts, aliases and proxies
+###
+
+# Per-page layout changes:
+#
+# With no layout
+# page "/path/to/file.html", :layout => false
+#
+# With alternative layout
+# page "/path/to/file.html", :layout => :otherlayout
+#
+# A path which all have the same layout
+# with_layout :admin do
+#   page "/admin/*"
+# end
+
+# Proxy pages (http://middlemanapp.com/basics/dynamic-pages/)
+# proxy "/this-page-has-no-template.html", "/template-file.html", :locals => {
+#  :which_fake_page => "Rendering a fake page with a local variable" }
+
+###
+# Helpers
+###
+
+# Automatic image dimensions on image_tag helper
+ activate :automatic_image_sizes
+
+# Reload the browser automatically whenever files change
+configure :development do
+  activate :livereload
+end
+
+# Methods defined in the helpers block are available in templates
+# helpers do
+#   def some_helper
+#     "Helping"
+#   end
+# end
+
+activate :syntax
+
+set :css_dir, 'stylesheets'
+
+set :js_dir, 'javascripts'
+
+set :images_dir, 'images'
+
+set :fonts_dir, 'fonts'
+
+set :markdown_engine, :redcarpet
+set :markdown, :fenced_code_blocks => true, :smartypants => true
+
+set :relative_links, true
+
+ignore "**/*.ttf"
+
+# Build-specific configuration
+configure :build do
+  # For example, change the Compass output style for deployment
+  # activate :minify_css
+
+  # Minify Javascript on build
+  # activate :minify_javascript
+
+  # Enable cache buster
+  # activate :asset_hash
+
+  # Use relative URLs
+  activate :relative_assets
+
+  # Or use a different image path
+  # set :http_prefix, "/Content/images/"
+end
diff --git a/src/doc/mkfonts.rb b/src/doc/mkfonts.rb
new file mode 100644 (file)
index 0000000..deb5ce4
--- /dev/null
@@ -0,0 +1,35 @@
+require "erb"
+
+def font(url, family, weight: weight, italic: italic)
+  url = "../fonts/#{url}.woff"
+
+  erb = ERB.new(<<-HERE.gsub(/^    /, ""), nil, "-")
+    @font-face {
+      src: url("#{url}");
+      font-family: "<%= family %>";
+      <%- if weight -%>
+      font-weight: <%= weight %>;
+      <%- end -%>
+      <%- if italic -%>
+      font-style: italic;
+      <%- end -%>
+    }
+
+  HERE
+
+  erb.result(binding)
+end
+
+File.open("source/stylesheets/fonts.css.scss", "w") do |file|
+  file.puts font("Consolas", "Consolas")
+  file.puts font("Consolas-Bold", "Consolas", weight: "bold")
+  file.puts font("Consolas-Italic", "Consolas", italic: true)
+  file.puts font("Consolas-Bold-Italic", "Consolas", weight: "bold", italic: true)
+
+  file.puts font("Roboto/Roboto-Thin", "Roboto", weight: 100)
+  file.puts font("Roboto/Roboto-Light", "Roboto", weight: 200)
+  file.puts font("Roboto/Roboto-Regular", "Roboto", weight: 400)
+  file.puts font("Roboto/Roboto-Medium", "Roboto", weight: 500)
+  file.puts font("Roboto/Roboto-Bold", "Roboto", weight: 700)
+  file.puts font("Roboto/Roboto-Black", "Roboto", weight: 800)
+end
diff --git a/src/doc/source/CNAME b/src/doc/source/CNAME
new file mode 100644 (file)
index 0000000..cbcca7c
--- /dev/null
@@ -0,0 +1 @@
+crates.io
diff --git a/src/doc/source/faq.md b/src/doc/source/faq.md
new file mode 100644 (file)
index 0000000..011f3e0
--- /dev/null
@@ -0,0 +1,116 @@
+---
+title: Frequently Asked Questions
+---
+
+# Is the plan to use Github as a package repository? <a href="#github" id="github" class="headerlink">¶</a>
+
+No. The plan for Cargo is to have a central registry of packages, like
+npm or Rubygems.
+
+We plan to support git repositories as a source of packages forever,
+because they can be used for early development and temporary patches,
+even when people use the registry as the primary source of packages.
+
+At the moment, the Rust team is still making regular changes to the
+language, and the Rust project recommends using nightly builds. This
+means that for now, package authors make regular changes in order to
+track the latest Rust. This makes downloading the latest `master` from
+Github the best approach to getting packages at the current point in the
+community's lifecycle.
+
+# Why build a package registry rather than use Github as a registry? <a href="#why-not-github" id="why-not-github" class="headerlink">¶</a>
+
+We think that it's very important to support multiple ways to download
+packages, including downloading from Github and copying packages into
+your project itself.
+
+That said, we think that a central registry offers a number of important
+benefits, and will likely become the primary way that people download
+packages in Cargo.
+
+For precedent, both Node.js's [npm][1] and Ruby's [bundler][2] support both a
+central registry model as well as a Git-based model, and most packages
+are downloaded through the registry in those ecosystems, with an
+important minority of packages making use of git-based packages.
+
+[1]: https://www.npmjs.org
+[2]: https://bundler.io
+
+Some of the advantages that make a central registry popular in other
+languages include:
+
+* **Discoverability**. A central registry provides an easy place to look
+  for existing packages. Combined with tagging, this also makes it
+  possible for a registry to provide ecosystem-wide information, such as a
+  list of the most popular or most-depended-on packages.
+* **Speed**. A central registry makes it possible to easily fetch just
+  the metadata for packages quickly and efficiently, and then to
+  efficiently download just the published package, and not other bloat
+  that happens to exist in the repository. This adds up to a significant
+  improvement in the speed of dependency resolution and fetching. As
+  dependency graphs scale up, downloading all of the git repositories bogs
+  down fast. Also remember that not everybody has a high-speed,
+  low-latency Internet connection.
+
+# Will Cargo work with C code (or other languages)? <a href="#c" id="c" class="headerlink">¶</a>
+
+Yes!
+
+Cargo handles compiling Rust code, but we know that many Rust projects
+link against C code. We also know that there are decades of tooling
+built up around compiling languages other than Rust.
+
+Our solution: Cargo allows a package to specify a script to run
+before invoking `rustc`. We plan to add support for platform-specific
+configuration, so you can use `make` on Linux and `cmake` on BSD, for
+example.
+
+# Can Cargo be used inside of `make` (or `ninja`, or ...) <a href="#make" id="make" class="headerlink">¶</a>
+
+Indeed. While we intend Cargo to be useful as a standalone way to
+compile Rust projects at the top-level, we know that some people will
+want to invoke Cargo from other build tools.
+
+We have designed Cargo to work well in those contexts, paying attention
+to things like error codes and machine-readable output modes. We still
+have some work to do on those fronts, but using Cargo in the context of
+conventional scripts is something we designed for from the beginning and
+will continue to prioritize.
+
+# Does Cargo handle multi-platform projects or cross-compilation? <a href="#multi-platform" id="multi-platform" class="headerlink">¶</a>
+
+Rust itself provides facilities for configuring sections of code based
+on the platform. We plan to support per-platform configuration in
+`Cargo.toml`, including platform-specific dependencies, in the near
+future.
+
+In the longer-term, we're looking at ways to conveniently cross-compile
+projects using Cargo.
+
+# Does Cargo support environments, like `production` or `test`? <a href="#environments" id="environments" class="headerlink">¶</a>
+
+We are planning on support environments in the near future, that can
+support:
+
+* environment-specific flags (like `-g --opt-level=0` for development
+  and `--opt-level=3` for production).
+* environment-specific dependencies (like `hamcrest` for test assertions).
+* environment-specific `#[cfg]`
+* a `cargo test` command
+
+We also plan to make it possible to specify "profiles", which can
+specify flags or dependencies for a combination of multiple environments
+and platforms ("use `fsevents`, but only in OSX in `development` or
+`test`").
+
+# Does Cargo work on Windows? <a href="#windows" id="windows" class="headerlink">¶</a>
+
+Yes!
+
+All commits to Cargo are required to pass the local test suite on Windows.
+If, however, you find a Windows issue, we consider it a bug, so [please file an
+issue][3].
+
+[3]: https://github.com/rust-lang/cargo/issues
+
+
diff --git a/src/doc/source/guide.md b/src/doc/source/guide.md
new file mode 100644 (file)
index 0000000..2ab9545
--- /dev/null
@@ -0,0 +1,398 @@
+---
+title: Guide
+---
+
+Welcome to the Cargo guide. This guide will give you all that you need to know
+about how to use Cargo to develop Rust projects.
+
+# Why Cargo exists
+
+Cargo is a tool that allows Rust projects to declare their various
+dependencies, and ensure that you'll always get a repeatable build.
+
+To accomplish this goal, Cargo does four things:
+
+* Introduces two metadata files with various bits of project information.
+* Fetches and builds your project's dependencies.
+* Invokes `rustc` or another build tool with the correct parameters to build your project.
+* Introduces conventions, making working with Rust projects easier.
+
+# Converting to Cargo
+
+You can convert an existing Rust project to use Cargo. You'll have to create a
+`Cargo.toml` file with all of your dependencies, and move your source files and
+test files into the places where Cargo expects them to be. See the [manifest
+description](/manifest.html) and the "Cargo Conventions" section below for more
+details.
+
+# Creating A New Project
+
+To start a new project with Cargo, use `cargo new`:
+
+```shell
+$ cargo new hello_world --bin
+```
+
+We're passing `--bin` because we're making a binary program: if we
+were making a library, we'd leave it off.
+
+Let's check out what Cargo has generated for us:
+
+```shell
+$ cd hello_world
+$ tree .
+.
+├── Cargo.toml
+└── src
+    â””── main.rs
+
+1 directory, 2 files
+```
+
+This is all we need to get started. First, let's check out `Cargo.toml`:
+
+```toml
+[package]
+
+name = "hello_world"
+version = "0.0.1"
+authors = ["Yehuda Katz <wycats@example.com>"]
+```
+
+This is called a **manifest**, and it contains all of the metadata that Cargo
+needs to compile your project. 
+
+Here's what's in `src/main.rs`:
+
+```rs
+fn main() {
+    println!("Hello world!")
+}
+```
+
+Cargo generated a 'hello world' for us. Let's compile it:
+
+<pre><code class="highlight"><span class="gp">$</span> cargo build
+<span style="font-weight: bold"
+class="s1">   Compiling</span> hello_world v0.0.1 (file:///Users/wycats/src/hello_world)</code></pre>
+
+And then run it:
+
+```shell
+$ ./target/hello_world
+Hello world!
+```
+
+We can also use `cargo run` to compile and then run it, all in one step:
+
+<pre><code class="highlight"><span class="gp">$</span> cargo run
+<span style="font-weight: bold"
+class="s1">   Fresh</span> hello-world v0.1.0 (file:///Users/wycats/src/hello_world)
+<span style="font-weight: bold"
+class="s1">   Running</span> `target/hello_world`
+Hello world!</code></pre>
+
+You'll now notice a new file, `Cargo.lock`. It contains information about our
+dependencies. Since we don't have any yet, it's not very interesting.
+
+# Working on an existing Cargo project
+
+If you download an existing project that uses Cargo, it's really easy
+to get going.
+
+First, get the project from somewhere. In this example, we'll use `color-rs`:
+
+```sh
+$ git clone https://github.com/bjz/color-rs.git
+$ cd color-rs
+```
+
+To build, just use `cargo build`:
+
+<pre><code class="highlight"><span class="gp">$</span> cargo build
+<span style="font-weight: bold" class="s1">   Compiling</span> color v0.0.1 (file:///Users/wycats/src/color-rs)</code></pre>
+
+This will fetch all of the dependencies and then build them, along with the
+project.
+
+# Adding Dependencies
+
+To depend on a library, add it to your `Cargo.toml`.
+
+```toml
+[package]
+
+name = "hello-world"
+version = "0.1.0"
+authors = ["Yehuda Katz <wycats@example.com>"]
+
+[dependencies.color]
+
+git = "https://github.com/bjz/color-rs.git"
+```
+
+You added the `color` library, which provides simple conversions
+between different color types.
+
+Now, you can pull in that library using `extern crate` in
+`main.rs`.
+
+```rs
+extern crate color;
+
+use color::{RGB, ToHSV};
+
+fn main() {
+    println!("Converting RGB to HSV!");
+    let red = RGB::new(255u8, 0, 0);
+    println!("HSV: {}", red.to_hsv::<f32>());
+}
+```
+
+Let's tell Cargo to fetch this new dependency and update the `Cargo.lock`:
+
+<pre><code class="highlight"><span class="gp">$</span> cargo update color
+<span style="font-weight: bold" class="s1">    Updating</span> git repository `https://github.com/bjz/color-rs.git`</code></pre>
+
+Compile it:
+
+<pre><code class="highlight"><span class="gp">$</span> cargo run
+<span style="font-weight: bold" class="s1">   Compiling</span> color v0.0.1 (https://github.com/bjz/color-rs.git#bf739419)
+<span style="font-weight: bold" class="s1">   Compiling</span> hello-world v0.1.0 (file:///Users/wycats/src/hello_world)
+<span style="font-weight: bold" class="s1">     Running</span> `target/hello_world`
+Converting RGB to HSV!
+HSV: HSV { h: 0, s: 1, v: 1 }</code></pre>
+
+We just specified a `git` repository for our dependency, but our `Cargo.lock`
+contains the exact information about which revision we used:
+
+```toml
+[root]
+name = "hello_world"
+version = "0.0.1"
+dependencies = [
+ "color 0.0.1 (git+https://github.com/bjz/color-rs.git#bf739419e2d31050615c1ba1a395b474269a4b98)",
+]
+
+[[package]]
+name = "color"
+version = "0.0.1"
+source = "git+https://github.com/bjz/color-rs.git#bf739419e2d31050615c1ba1a395b474269a4b98"
+
+```
+
+Now, if `color-rs` gets updated, we will still build with the same revision, until
+we choose to `cargo update` again.
+
+# Cargo Conventions
+
+Cargo uses conventions to make it easy to dive into a new Cargo project. Here
+are the conventions that Cargo uses:
+
+* `Cargo.toml` and `Cargo.lock` are stored in the root of your project.
+* Source code goes in the `src` directory.
+* External tests go in the `tests` directory.
+* The default executable file is `src/main.rs`.
+* Other executables can be placed in `src/bin/*.rs`.
+* The default library file is `src/lib.rs`.
+
+# Cargo.toml vs Cargo.lock
+
+`Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk
+about them, here's a summary:
+
+* `Cargo.toml` is about describing your dependencies in a broad sense, and is written by you.
+* `Cargo.lock` contains exact information about your dependencies, and is maintained by Cargo.
+* If you're building a library, put `Cargo.lock` in your `.gitignore`.
+* If you're building an executable, check `Cargo.lock` into `git`.
+
+Let's dig in a little bit more.
+
+`Cargo.toml` is a **manifest** file. In the manifest, we can specify a bunch of
+different metadata about our project. For example, we can say that we depend
+on another project:
+
+```toml
+[package]
+
+name = "hello_world"
+version = "0.0.1"
+authors = ["Yehuda Katz <wycats@example.com>"]
+
+[dependencies.color]
+
+git = "https://github.com/bjz/color-rs.git"
+```
+
+This project has a single dependency, on the `color` library. We've stated in
+this case that we're relying on a particular Git repository that lives on
+GitHub. Since we haven't specified any other information, Cargo assumes that
+we intend to use the latest commit on the `master` branch to build our project.
+
+Sound good? Well, there's one problem: If you build this project today, and
+then you send a copy to me, and I build this project tomorrow, something bad
+could happen. `bjz` could update `color-rs` in the meantime, and my build would
+include this commit, while yours would not. Therefore, we would get different
+builds. This would be bad, because we want reproducible builds.
+
+We could fix this problem by putting a `rev` line in our `Cargo.toml`:
+
+```toml
+[dependencies.color]
+
+git = "https://github.com/bjz/color-rs.git"
+rev = "bf739419e2d31050615c1ba1a395b474269a4"
+```
+
+Now, our builds will be the same. But, there's a big drawback: now we have to
+manually think about SHA-1s every time we want to update our library. This is
+both tedius and error prone.
+
+Enter the `Cargo.lock`. Because of its existence, we don't need to manually
+keep track of the exact revisions: Cargo will do it for us. When we have a
+manifest like this:
+
+```toml
+[package]
+
+name = "hello_world"
+version = "0.0.1"
+authors = ["Yehuda Katz <wycats@example.com>"]
+
+[dependencies.color]
+
+git = "https://github.com/bjz/color-rs.git"
+```
+
+Cargo will take the latest commit, and write that information out into our
+`Cargo.lock` when we build for the first time. That file will look like this:
+
+```toml
+[root]
+name = "hello_world"
+version = "0.0.1"
+dependencies = [
+ "color 0.0.1 (git+https://github.com/bjz/color-rs.git#bf739419e2d31050615c1ba1a395b474269a4b98)",
+]
+
+[[package]]
+name = "color"
+version = "0.0.1"
+source = "git+https://github.com/bjz/color-rs.git#bf739419e2d31050615c1ba1a395b474269a4b98"
+
+```
+
+You can see that there's a lot more information here, including the exact
+revision we used to build. Now, when you give your project to someone else,
+they'll use the exact same SHA, even though we didn't specify it in our
+`Cargo.toml`.
+
+When we're ready to opt in to a new version of the library, Cargo can
+re-calculate the dependencies, and update things for us:
+
+```shell
+$ cargo update       # updates all dependencies
+$ cargo update color # updtes just 'color'
+```
+
+This will write out a new `Cargo.lock` with the new version information.
+
+# Overriding Dependencies
+
+Sometimes, you may want to override one of Cargo's dependencies. For example,
+let's say you're working on a project, `conduit-static`, which depends on
+the package `conduit`. You find a bug in `conduit`, and you want to write a
+patch. Here's what `conduit-static`'s `Cargo.toml` looks like:
+
+```toml
+[package]
+
+name = "conduit-static"
+version = "0.1.0"
+authors = ["Yehuda Katz <wycats@example.com>"]
+
+[dependencies.conduit]
+
+git = "https://github.com/conduit-rust/conduit.git"
+```
+
+You check out a local copy of `conduit`, let's say in your `~/src` directory:
+
+```shell
+$ cd ~/src
+$ git clone https://github.com/conduit-rust/conduit.git
+```
+
+You'd like to have `conduit-static` use your local version of `conduit`,
+rather than the one on GitHub, while you fix the bug.
+
+Cargo solves this problem by allowing you to have a local configuration
+that specifies an **override**. If Cargo finds this configuration when
+building your package, it will use the override on your local machine
+instead of the source specified in your `Cargo.toml`.
+
+Cargo looks for a directory named `.cargo` up the directory hierarchy of
+your project. If your project is in `/Users/wycats/src/conduit-static`,
+it will search for a `.cargo` in:
+
+* `/Users/wycats/src/conduit-static`
+* `/Users/wycats/src`
+* `/Users/wycats`
+* `/Users`
+* `/`
+
+This allows you to specify your overrides in a parent directory that
+includes commonly used packages that you work on locally, and share them
+with all projects.
+
+To specify overrides, create a `.cargo/config` file in some ancestor of
+your project's directory (common places to put it is in the root of
+your code directory or in your home directory).
+
+Inside that file, put this:
+
+```
+paths = ["/Users/wycats/src/conduit"]
+```
+
+This array should be filled with directories that contain a `Cargo.toml`. In
+this instance, we're just adding `conduit`, so it will be the only one that's
+overridden.
+
+# Tests
+
+Cargo can run your tests with the `cargo test` command. Cargo runs tests in two
+places: in each of your `src` files, and any tests in `tests/`. Tests
+in your `src` files should be unit tests, and tests in `tests/` should be
+integration-style tests. As such, you'll need to import your crates into
+the files in `tests`.
+
+To run your tests, just run `cargo test`:
+
+<pre><code class="highlight"><span class="gp">$</span> cargo test
+<span style="font-weight: bold"
+class="s1">   Compiling</span> color v0.0.1 (https://github.com/bjz/color-rs.git#bf739419)
+<span style="font-weight: bold"
+class="s1">   Compiling</span> hello-world v0.0.1 (file:///Users/wycats/src/hello_world)
+<span style="font-weight: bold"
+class="s1">     Running</span> target/test/hello_world-9c2b65bbb79eabce
+
+running 0 tests
+
+test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured
+</code></pre>
+
+Of course, if your project has tests, you'll see more output, with the
+correct number of tests.
+
+## Travis-CI
+
+To test your project on Travis-CI, here is a sample `.travis.yml` file:
+
+```
+install:
+  - curl http://www.rust-lang.org/rustup.sh | sudo sh -
+script:
+  - cargo build --verbose
+  - cargo test --verbose
+```
diff --git a/src/doc/source/images/Cargo-Logo-Small.png b/src/doc/source/images/Cargo-Logo-Small.png
new file mode 100644 (file)
index 0000000..eca9665
Binary files /dev/null and b/src/doc/source/images/Cargo-Logo-Small.png differ
diff --git a/src/doc/source/images/forkme.png b/src/doc/source/images/forkme.png
new file mode 100644 (file)
index 0000000..100aad0
Binary files /dev/null and b/src/doc/source/images/forkme.png differ
diff --git a/src/doc/source/images/noise.png b/src/doc/source/images/noise.png
new file mode 100644 (file)
index 0000000..545d930
Binary files /dev/null and b/src/doc/source/images/noise.png differ
diff --git a/src/doc/source/index.md b/src/doc/source/index.md
new file mode 100644 (file)
index 0000000..8ac8f2e
--- /dev/null
@@ -0,0 +1,91 @@
+---
+title: Cargo, Rust's Package Manager
+---
+
+# Installing
+
+The easiest way to get Cargo is to get the Rust nightly build by using
+the `rustup` script:
+
+```shell
+$ curl https://static.rust-lang.org/rustup.sh | sudo bash
+```
+
+This will get you the latest Rust nightly for your platform along with
+the latest Cargo. You should run this script almost every day to get the latest updates.
+   
+If you are on Windows, you can directly download the latest [Rust](http://static.rust-lang.org/dist/rust-nightly-install.exe)
+and [Cargo](http://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-mingw32.tar.gz) nightlies.  
+
+Alternatively, you can build Cargo from source.
+
+# Let's Get Started
+
+To start a new project with Cargo, use `cargo new`:
+
+```shell
+$ cargo new hello_world --bin
+```
+
+We're passing `--bin` because we're making a binary program: if we
+were making a library, we'd leave it off.
+
+Let's check out what Cargo has generated for us:
+
+```shell
+$ cd hello_world
+$ tree .
+.
+├── Cargo.toml
+└── src
+    â””── main.rs
+
+1 directory, 2 files
+```
+
+This is all we need to get started. First, let's check out `Cargo.toml`:
+
+```toml
+[package]
+
+name = "hello_world"
+version = "0.0.1"
+authors = ["Yehuda Katz <wycats@example.com>"]
+```
+
+This is called a **manifest**, and it contains all of the metadata that Cargo
+needs to compile your project. 
+
+Here's what's in `src/main.rs`:
+
+```rs
+fn main() {
+    println!("Hello world!")
+}
+```
+
+Cargo generated a 'hello world' for us. Let's compile it:
+
+<pre><code class="highlight"><span class="gp">$</span> cargo build
+<span style="font-weight: bold"
+class="s1">   Compiling</span> hello_world v0.0.1 (file:///Users/wycats/src/hello_world)</code></pre>
+
+And then run it:
+
+```shell
+$ ./target/hello_world
+Hello world!
+```
+
+We can also use `cargo run` to compile and then run it, all in one step:
+
+<pre><code class="highlight"><span class="gp">$</span> cargo run
+<span style="font-weight: bold"
+class="s1">   Fresh</span> hello-world v0.1.0 (file:///Users/wycats/src/hello_world)
+<span style="font-weight: bold"
+class="s1">   Running</span> `target/hello_world`
+Hello world!</code></pre>
+
+# Going Further
+
+For more details on using Cargo, check out the [Cargo Guide](/guide.html)
diff --git a/src/doc/source/javascripts/all.js b/src/doc/source/javascripts/all.js
new file mode 100644 (file)
index 0000000..2becd76
--- /dev/null
@@ -0,0 +1 @@
+//= require_tree .
\ No newline at end of file
diff --git a/src/doc/source/layouts/layout.erb b/src/doc/source/layouts/layout.erb
new file mode 100644 (file)
index 0000000..4c6a8d9
--- /dev/null
@@ -0,0 +1,34 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    
+    <!-- Always force latest IE rendering engine or request Chrome Frame -->
+    <meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible">
+    
+    <!-- Use title if it's in the page YAML frontmatter -->
+    <title><%= current_page.data.title || "The Middleman" %></title>
+    
+    <%= stylesheet_link_tag "all" %>
+    <%= javascript_include_tag  "all" %>
+  </head>
+  
+  <body class="<%= page_classes %>">
+    <%= link_to image_tag("forkme.png", class: "fork-me"), "https://github.com/rust-lang/cargo" %>
+    <%= link_to image_tag("Cargo-Logo-Small.png", class: "logo"), "index.html" %>
+
+    <main>
+      <p>Cargo downloads your <a href="http://rust-lang.org">Rust</a> project's dependencies and builds your project</p>
+
+      <%= yield %>
+
+      <footer>
+        <%= link_to "Guide", "guide.html" %> |
+        <%= link_to "Frequently Asked Questions", "faq.html" %> |
+        <%= link_to "Manifest Format", "manifest.html" %> |
+        <%= link_to "Building Non-Rust Code", "native-build.html" %>
+      </footer>
+    </main>
+
+  </body>
+</html>
diff --git a/src/doc/source/manifest.md b/src/doc/source/manifest.md
new file mode 100644 (file)
index 0000000..4047a98
--- /dev/null
@@ -0,0 +1,130 @@
+---
+title: The Manifest Format
+---
+
+# The `[package]` Section
+
+The first section in a `Cargo.toml` is `[package]`.
+
+```toml
+[package]
+name = "hello-world" # the name of the package
+version = "1.0.0"    # the current version, obeying semver
+authors = [ "wycats@example.com" ]
+```
+
+All three of these fields are mandatory. Cargo bakes in the concept of
+[Semantic Versioning](http://semver.org/), so make sure you follow some
+basic rules:
+
+* Before you reach 1.0.0, anything goes.
+* After 1.0.0, only make breaking changes when you increment the major
+  version. In Rust, breaking changes include adding fields to structs or
+  variants to enums. Don't break the build.
+* After 1.0.0, don't add any new public API (no new `pub` anything) in
+  tiny versions. Always increment the minor version if you add any new
+  `pub` structs, traits, fields, types, functions, methods or anything else.
+* Use version numbers with three numeric parts such as 1.0.0 rather than 1.0.
+
+## The `build` Field (optional)
+
+You can specify a script that Cargo should execute before invoking
+`rustc`. You can use this to compile C code that you will [link][1] into
+your Rust code, for example.
+
+[1]: http://doc.rust-lang.org/rust.html#external-blocks
+
+```toml
+[package]
+# ...
+build = "make"
+```
+
+# The `[dependencies.*]` Sections
+
+You list dependencies using `[dependencies.<name>]`. For example, if you
+wanted to depend on both `hammer` and `color`:
+
+```toml
+[package]
+# ...
+
+[dependencies.hammer]
+version = "0.5.0" # optional
+git = "https://github.com/wycats/hammer.rs"
+
+[dependencies.color]
+git = "https://github.com/bjz/color-rs"
+```
+
+You can specify the source of a dependency in one of two ways at the moment:
+
+* `git = "<git-url>"`: A git repository with a `Cargo.toml` in its root. The
+  `rev`, `tag`, and `branch` options are also recognized to use something other
+  than the `master` branch.
+* `path = "<relative-path>"`: A path relative to the current `Cargo.toml`
+  with a `Cargo.toml` in its root.
+
+Soon, you will be able to load packages from the Cargo registry as well.
+
+# The Project Layout
+
+If your project is an executable, name the main source file `src/main.rs`.
+If it is a library, name the main source file `src/lib.rs`.
+
+Cargo will also treat any files located in `src/bin/*.rs` as
+executables.
+
+When you run `cargo build`, Cargo will compile all of these files into
+the `target` directory.
+
+```
+â–¾ src/          # directory containing source files
+  â–¾ bin/        # (optional) directory containing executables
+    *.rs
+  lib.rs        # the main entry point for libraries and packages
+  main.rs       # the main entry point for projects producing executables
+â–¾ examples/     # (optional) examples
+  *.rs
+â–¾ tests/        # (optional) integration tests
+  *.rs
+```
+
+# Examples
+
+Files located under `examples` are example uses of the functionality
+provided by the library.
+
+They must compile as executables (with `main.rs`) and load in the
+library by using `extern crate <library-name>`. They are compiled when
+you run your tests to protect them from bitrotting.
+
+# Tests
+
+When you run `cargo test`, Cargo will:
+
+* Compile your library's unit tests, which are in files reachable from
+  `lib.rs`. Any sections marked with `#[cfg(test)]` will be included.
+* Compile your library's integration tests, which are located in
+  `tests`. Files in `tests` load in your library by using `extern crate
+  <library-name>` like any other code that depends on it.
+* Compile your library's examples.
+
+# Building Dynamic Libraries
+
+If your project produces a library, you can specify which kind of
+library to build by explicitly listing the library in your `Cargo.toml`:
+
+```toml
+# ...
+
+[[lib]]
+
+name = "..."
+crate-types = [ "dylib" ]
+```
+
+The available options are `dylib` and `rlib`. You should only use
+this option in a project. Cargo will always compile **packages**
+(dependencies) based on the requirements of the project that includes
+them.
diff --git a/src/doc/source/native-build.md b/src/doc/source/native-build.md
new file mode 100644 (file)
index 0000000..cbee444
--- /dev/null
@@ -0,0 +1,60 @@
+---
+title: Building external code
+---
+
+Some packages need to compile third-party non-Rust code that you will
+link into your Rust code using `#[link]` (more information on `#[link]`
+can be found in [the Rust manual][1]).
+
+Cargo does not aim to replace other tools that are well-optimized for
+building C or C++ code, but it does integrate with them with the `build`
+configuration option.
+
+```toml
+[package]
+
+name = "hello-world-from-c"
+version = "0.1.0"
+authors = [ "wycats@gmail.com" ]
+build = "make"
+```
+
+The `build` command will be invoked before `rustc`, allowing your Rust
+code to depend on the built artifacts.
+
+Here's what you need to know:
+
+* Cargo passes your build script an environment variable named
+  `OUT_DIR`, which is where you should put any compiled artifacts. It
+  will be different for different Cargo commands, but Cargo will always
+  pass that output directory as a lib directory to `rustc`.
+* Cargo will retain all output in `OUT_DIR` for clean packages across
+  builds (intelligently discarding the compiled artifacts for dirty
+  dependencies). Do not put the output of a build command in any other
+  directory.
+* The actual location of `$OUT_DIR` is
+  `/path/to/project/target/native/$your-out-dir`.
+
+What this means is that the normal workflow for build dependencies is:
+
+* The first time a user types `cargo build` for a project that contains
+  your package, your `build` script will be invoked. Place any artifacts
+  into the provided `$OUT_DIR`.
+* The next time a user runs `cargo build`, if the dependency has not
+  changed (via `cargo update <your-package>`), Cargo will reuse the
+  output you provided before.
+* If the user updates your package to a new version (or git revision),
+  Cargo will wipe the old `$OUT_DIR` and re-invoke your build script.
+
+In general, build scripts may not be as portable as we'd like today. We
+encourage package authors to write build scripts that can work in both
+Windows and Unix environments.
+
+Several people who work on Cargo are also working on a project called
+[link-config][2], which is a Rust syntax extension whose goal is to
+enable portable external compilation and linkage against system
+packages. We intend for it to eventually serve this purpose for Cargo
+projects.
+
+[1]: http://doc.rust-lang.org/rust.html#runtime-services,-linkage-and-debugging
+[2]: https://github.com/alexcrichton/link-config
diff --git a/src/doc/source/stylesheets/all.css.scss b/src/doc/source/stylesheets/all.css.scss
new file mode 100644 (file)
index 0000000..bee9586
--- /dev/null
@@ -0,0 +1,167 @@
+@charset "utf-8";
+@import "compass/reset";
+@import "compass/css3/images";
+@import "fonts";
+@import "solarized";
+@import "colors";
+
+html {
+  @include background(image-url("noise.png"), radial-gradient(top
+  center, circle, $light-green 0%, $dark-green 750px));
+}
+
+pre {
+  font-family: "Consolas";
+}
+
+body {
+  font-family: "Roboto";
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+a {
+  color: $orange;
+
+  &:hover {
+    color: $purple;
+  }
+}
+
+h1 {
+  font-size: 24px;
+  margin: 20px 0 10px 0;
+  font-weight: bold;
+  color: $purple;
+
+  code:not(.highlight) {
+    color: darken($orange, 5%);
+    vertical-align: bottom;
+  }
+
+  &:hover {
+    .headerlink {
+      display: inline-block;
+    }
+  }
+}
+
+h1:first-child {
+  margin-top: 0;
+}
+
+h2 {
+  font-size: 18px;
+  margin: 15px 0 5px 0;
+  color: $purple;
+  font-weight: bold;
+
+  code:not(.highlight) {
+    color: darken($orange, 5%);
+  }
+}
+
+code:not(.highlight) {
+  font-family: Consolas;
+  color: $purple;
+}
+
+main {
+  display: flex;
+  flex-direction: column;
+
+  max-width: 900px;
+  margin-bottom: 10px;
+
+  background-color: $cream;
+  padding: 15px;
+  border-radius: 5px;
+  box-shadow: 0px 0px 5px 2px $dark-green;
+
+  p:first-child {
+    color: $light-green;
+    font-weight: 500;
+    margin-top: 3px;
+    padding-bottom: 15px;
+    border-bottom: 1px solid $second-green;
+    text-align: center;
+
+    a {
+      color: $dark-green;
+
+      &:hover {
+        color: $second-green;
+      }
+    }
+  }
+
+  p, ul {
+    color: $dark-green;
+    margin: 10px 0;
+    line-height: 150%;
+  }
+
+  ul {
+    margin-left: 20px;
+  }
+
+  li {
+    list-style-type: disc;
+  }
+
+  strong {
+    font-weight: bold;
+  }
+}
+
+img.logo {
+  align-self: center;
+  margin-bottom: 10px;
+}
+
+pre {
+  background: $beige;
+  padding: 10px;
+  margin: 10px 0;
+  border: 1px solid lighten(#93a1a1, 20%);
+  border-radius: 4px;
+  line-height: 120%;
+  max-width: calc(100vw - 45px);
+  overflow-x: auto;
+}
+
+footer {
+  margin-top: 10px;
+  border-top: 1px solid $purple;
+  padding-top: 10px;
+  width: 100%;
+  text-align: center;
+
+  a {
+    color: $purple;
+    text-decoration: none;
+
+    &:hover {
+      text-decoration: underline;
+    }
+  }
+}
+
+.headerlink {
+  display: none;
+  text-decoration: none;
+}
+
+.fork-me {
+  position:absolute;
+  top:0;
+  right:0;
+}
diff --git a/src/doc/source/stylesheets/colors.css.scss b/src/doc/source/stylesheets/colors.css.scss
new file mode 100644 (file)
index 0000000..08a8e12
--- /dev/null
@@ -0,0 +1,12 @@
+// primary
+$dark-green: #3B6837;
+$light-green: #199B5C;
+$purple: #B64790;
+$orange: #F3BB00;
+
+// secondary
+$second-green: #62865F;
+$beige: #EEECDD;
+$cream: #F9F7EC;
+$dark-cream: #FFF2C8;
+
diff --git a/src/doc/source/stylesheets/fonts.css.scss b/src/doc/source/stylesheets/fonts.css.scss
new file mode 100644 (file)
index 0000000..d65b3d2
--- /dev/null
@@ -0,0 +1,39 @@
+@import "compass/css3";
+
+@include font-face("Consolas", inline-font-files("Consolas.woff", woff), $weight: 400);
+@include font-face("Consolas", inline-font-files("Consolas-Bold.woff", woff), $weight: 700);
+@include font-face("Roboto", inline-font-files("Roboto/Roboto-Regular.woff", woff), $weight: 400);
+@include font-face("Roboto", inline-font-files("Roboto/Roboto-Bold.woff", woff), $weight: 700);
+@include font-face("Roboto", inline-font-files("Roboto/Roboto-Medium.woff", woff), $weight: 500);
+
+@font-face {
+  src: url("../fonts/Consolas-Italic.woff");
+  font-family: "Consolas";
+  font-style: italic;
+}
+
+@font-face {
+  src: url("../fonts/Consolas-Bold-Italic.woff");
+  font-family: "Consolas";
+  font-weight: bold;
+  font-style: italic;
+}
+
+@font-face {
+  src: url("../fonts/Roboto/Roboto-Thin.woff");
+  font-family: "Roboto";
+  font-weight: 100;
+}
+
+@font-face {
+  src: url("../fonts/Roboto/Roboto-Light.woff");
+  font-family: "Roboto";
+  font-weight: 200;
+}
+
+@font-face {
+  src: url("../fonts/Roboto/Roboto-Black.woff");
+  font-family: "Roboto";
+  font-weight: 800;
+}
+
diff --git a/src/doc/source/stylesheets/normalize.css b/src/doc/source/stylesheets/normalize.css
new file mode 100644 (file)
index 0000000..73abb76
--- /dev/null
@@ -0,0 +1,375 @@
+/*! normalize.css v2.0.1 | MIT License | git.io/normalize */
+
+/* ==========================================================================
+   HTML5 display definitions
+   ========================================================================== */
+
+/*
+ * Corrects `block` display not defined in IE 8/9.
+ */
+
+article,
+aside,
+details,
+figcaption,
+figure,
+footer,
+header,
+hgroup,
+nav,
+section,
+summary {
+    display: block;
+}
+
+/*
+ * Corrects `inline-block` display not defined in IE 8/9.
+ */
+
+audio,
+canvas,
+video {
+    display: inline-block;
+}
+
+/*
+ * Prevents modern browsers from displaying `audio` without controls.
+ * Remove excess height in iOS 5 devices.
+ */
+
+audio:not([controls]) {
+    display: none;
+    height: 0;
+}
+
+/*
+ * Addresses styling for `hidden` attribute not present in IE 8/9.
+ */
+
+[hidden] {
+    display: none;
+}
+
+/* ==========================================================================
+   Base
+   ========================================================================== */
+
+/*
+ * 1. Sets default font family to sans-serif.
+ * 2. Prevents iOS text size adjust after orientation change, without disabling
+ *    user zoom.
+ */
+
+html {
+    font-family: sans-serif; /* 1 */
+    -webkit-text-size-adjust: 100%; /* 2 */
+    -ms-text-size-adjust: 100%; /* 2 */
+}
+
+/*
+ * Removes default margin.
+ */
+
+body {
+    margin: 0;
+}
+
+/* ==========================================================================
+   Links
+   ========================================================================== */
+
+/*
+ * Addresses `outline` inconsistency between Chrome and other browsers.
+ */
+
+a:focus {
+    outline: thin dotted;
+}
+
+/*
+ * Improves readability when focused and also mouse hovered in all browsers.
+ */
+
+a:active,
+a:hover {
+    outline: 0;
+}
+
+/* ==========================================================================
+   Typography
+   ========================================================================== */
+
+/*
+ * Addresses `h1` font sizes within `section` and `article` in Firefox 4+,
+ * Safari 5, and Chrome.
+ */
+
+h1 {
+    font-size: 2em;
+}
+
+/*
+ * Addresses styling not present in IE 8/9, Safari 5, and Chrome.
+ */
+
+abbr[title] {
+    border-bottom: 1px dotted;
+}
+
+/*
+ * Addresses style set to `bolder` in Firefox 4+, Safari 5, and Chrome.
+ */
+
+b,
+strong {
+    font-weight: bold;
+}
+
+/*
+ * Addresses styling not present in Safari 5 and Chrome.
+ */
+
+dfn {
+    font-style: italic;
+}
+
+/*
+ * Addresses styling not present in IE 8/9.
+ */
+
+mark {
+    background: #ff0;
+    color: #000;
+}
+
+
+/*
+ * Corrects font family set oddly in Safari 5 and Chrome.
+ */
+
+code,
+kbd,
+pre,
+samp {
+    font-family: monospace, serif;
+    font-size: 1em;
+}
+
+/*
+ * Improves readability of pre-formatted text in all browsers.
+ */
+
+pre {
+    white-space: pre;
+    white-space: pre-wrap;
+    word-wrap: break-word;
+}
+
+/*
+ * Sets consistent quote types.
+ */
+
+q {
+    quotes: "\201C" "\201D" "\2018" "\2019";
+}
+
+/*
+ * Addresses inconsistent and variable font size in all browsers.
+ */
+
+small {
+    font-size: 80%;
+}
+
+/*
+ * Prevents `sub` and `sup` affecting `line-height` in all browsers.
+ */
+
+sub,
+sup {
+    font-size: 75%;
+    line-height: 0;
+    position: relative;
+    vertical-align: baseline;
+}
+
+sup {
+    top: -0.5em;
+}
+
+sub {
+    bottom: -0.25em;
+}
+
+/* ==========================================================================
+   Embedded content
+   ========================================================================== */
+
+/*
+ * Removes border when inside `a` element in IE 8/9.
+ */
+
+img {
+    border: 0;
+}
+
+/*
+ * Corrects overflow displayed oddly in IE 9.
+ */
+
+svg:not(:root) {
+    overflow: hidden;
+}
+
+/* ==========================================================================
+   Figures
+   ========================================================================== */
+
+/*
+ * Addresses margin not present in IE 8/9 and Safari 5.
+ */
+
+figure {
+    margin: 0;
+}
+
+/* ==========================================================================
+   Forms
+   ========================================================================== */
+
+/*
+ * Define consistent border, margin, and padding.
+ */
+
+fieldset {
+    border: 1px solid #c0c0c0;
+    margin: 0 2px;
+    padding: 0.35em 0.625em 0.75em;
+}
+
+/*
+ * 1. Corrects color not being inherited in IE 8/9.
+ * 2. Remove padding so people aren't caught out if they zero out fieldsets.
+ */
+
+legend {
+    border: 0; /* 1 */
+    padding: 0; /* 2 */
+}
+
+/*
+ * 1. Corrects font family not being inherited in all browsers.
+ * 2. Corrects font size not being inherited in all browsers.
+ * 3. Addresses margins set differently in Firefox 4+, Safari 5, and Chrome
+ */
+
+button,
+input,
+select,
+textarea {
+    font-family: inherit; /* 1 */
+    font-size: 100%; /* 2 */
+    margin: 0; /* 3 */
+}
+
+/*
+ * Addresses Firefox 4+ setting `line-height` on `input` using `!important` in
+ * the UA stylesheet.
+ */
+
+button,
+input {
+    line-height: normal;
+}
+
+/*
+ * 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio`
+ *    and `video` controls.
+ * 2. Corrects inability to style clickable `input` types in iOS.
+ * 3. Improves usability and consistency of cursor style between image-type
+ *    `input` and others.
+ */
+
+button,
+html input[type="button"], /* 1 */
+input[type="reset"],
+input[type="submit"] {
+    -webkit-appearance: button; /* 2 */
+    cursor: pointer; /* 3 */
+}
+
+/*
+ * Re-set default cursor for disabled elements.
+ */
+
+button[disabled],
+input[disabled] {
+    cursor: default;
+}
+
+/*
+ * 1. Addresses box sizing set to `content-box` in IE 8/9.
+ * 2. Removes excess padding in IE 8/9.
+ */
+
+input[type="checkbox"],
+input[type="radio"] {
+    box-sizing: border-box; /* 1 */
+    padding: 0; /* 2 */
+}
+
+/*
+ * 1. Addresses `appearance` set to `searchfield` in Safari 5 and Chrome.
+ * 2. Addresses `box-sizing` set to `border-box` in Safari 5 and Chrome
+ *    (include `-moz` to future-proof).
+ */
+
+input[type="search"] {
+    -webkit-appearance: textfield; /* 1 */
+    -moz-box-sizing: content-box;
+    -webkit-box-sizing: content-box; /* 2 */
+    box-sizing: content-box;
+}
+
+/*
+ * Removes inner padding and search cancel button in Safari 5 and Chrome
+ * on OS X.
+ */
+
+input[type="search"]::-webkit-search-cancel-button,
+input[type="search"]::-webkit-search-decoration {
+    -webkit-appearance: none;
+}
+
+/*
+ * Removes inner padding and border in Firefox 4+.
+ */
+
+button::-moz-focus-inner,
+input::-moz-focus-inner {
+    border: 0;
+    padding: 0;
+}
+
+/*
+ * 1. Removes default vertical scrollbar in IE 8/9.
+ * 2. Improves readability and alignment in all browsers.
+ */
+
+textarea {
+    overflow: auto; /* 1 */
+    vertical-align: top; /* 2 */
+}
+
+/* ==========================================================================
+   Tables
+   ========================================================================== */
+
+/*
+ * Remove most spacing between table cells.
+ */
+
+table {
+    border-collapse: collapse;
+    border-spacing: 0;
+}
\ No newline at end of file
diff --git a/src/doc/source/stylesheets/solarized.css.scss b/src/doc/source/stylesheets/solarized.css.scss
new file mode 100644 (file)
index 0000000..0c76570
--- /dev/null
@@ -0,0 +1,71 @@
+@import "colors";
+
+.highlight { background-color: $beige; color: #586E75 }
+.highlight .c { color: #93A1A1 } /* Comment */
+.highlight .err { color: #93A1A1 } /* Error */
+.highlight .g { color: #93A1A1 } /* Generic */
+.highlight .k { color: #859900 } /* Keyword */
+.highlight .l { color: #93A1A1 } /* Literal */
+.highlight .n { color: #CB4B16 } /* Name */
+.highlight .o { color: #859900 } /* Operator */
+.highlight .x { color: #CB4B16 } /* Other */
+.highlight .p { color: #586E75 } /* Punctuation */
+.highlight .cm { color: #586E75 } /* Comment.Multiline */
+.highlight .cp { color: #859900 } /* Comment.Preproc */
+.highlight .c1 { color: #586E75 } /* Comment.Single */
+.highlight .cs { color: #859900 } /* Comment.Special */
+.highlight .gd { color: #2AA198 } /* Generic.Deleted */
+.highlight .ge { color: #93A1A1; font-style: italic } /* Generic.Emph */
+.highlight .gr { color: #DC322F } /* Generic.Error */
+.highlight .gh { color: #CB4B16 } /* Generic.Heading */
+.highlight .gi { color: #859900 } /* Generic.Inserted */
+.highlight .go { color: #93A1A1 } /* Generic.Output */
+.highlight .gp { color: #93A1A1 } /* Generic.Prompt */
+.highlight .gs { color: #93A1A1; font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #CB4B16 } /* Generic.Subheading */
+.highlight .gt { color: #93A1A1 } /* Generic.Traceback */
+.highlight .kc { color: #CB4B16 } /* Keyword.Constant */
+.highlight .kd { color: #268BD2 } /* Keyword.Declaration */
+.highlight .kn { color: #859900 } /* Keyword.Namespace */
+.highlight .kp { color: #859900 } /* Keyword.Pseudo */
+.highlight .kr { color: #268BD2 } /* Keyword.Reserved */
+.highlight .kt { color: #DC322F } /* Keyword.Type */
+.highlight .ld { color: #93A1A1 } /* Literal.Date */
+.highlight .m { color: #2AA198 } /* Literal.Number */
+.highlight .s { color: #2AA198 } /* Literal.String */
+.highlight .na { color: #93A1A1 } /* Name.Attribute */
+.highlight .nb { color: #B58900 } /* Name.Builtin */
+.highlight .nc { color: #268BD2 } /* Name.Class */
+.highlight .no { color: #CB4B16 } /* Name.Constant */
+.highlight .nd { color: #268BD2 } /* Name.Decorator */
+.highlight .ni { color: #CB4B16 } /* Name.Entity */
+.highlight .ne { color: #CB4B16 } /* Name.Exception */
+.highlight .nf { color: #268BD2 } /* Name.Function */
+.highlight .nl { color: #93A1A1 } /* Name.Label */
+.highlight .nn { color: #CB4B16 } /* Name.Namespace */
+.highlight .nx { color: #93A1A1 } /* Name.Other */
+.highlight .py { color: #268BD2 } /* Name.Property */
+.highlight .nt { color: #268BD2 } /* Name.Tag */
+.highlight .nv { color: #268BD2 } /* Name.Variable */
+.highlight .ow { color: #859900 } /* Operator.Word */
+.highlight .w { color: #93A1A1 } /* Text.Whitespace */
+.highlight .mf { color: #2AA198 } /* Literal.Number.Float */
+.highlight .mh { color: #2AA198 } /* Literal.Number.Hex */
+.highlight .mi { color: #2AA198 } /* Literal.Number.Integer */
+.highlight .mo { color: #2AA198 } /* Literal.Number.Oct */
+.highlight .sb { color: #586E75 } /* Literal.String.Backtick */
+.highlight .sc { color: #2AA198 } /* Literal.String.Char */
+.highlight .sd { color: #93A1A1 } /* Literal.String.Doc */
+.highlight .s2 { color: #2AA198 } /* Literal.String.Double */
+.highlight .se { color: #CB4B16 } /* Literal.String.Escape */
+.highlight .sh { color: #93A1A1 } /* Literal.String.Heredoc */
+.highlight .si { color: #2AA198 } /* Literal.String.Interpol */
+.highlight .sx { color: #2AA198 } /* Literal.String.Other */
+.highlight .sr { color: #DC322F } /* Literal.String.Regex */
+.highlight .s1 { color: #2AA198 } /* Literal.String.Single */
+.highlight .ss { color: #2AA198 } /* Literal.String.Symbol */
+.highlight .bp { color: #268BD2 } /* Name.Builtin.Pseudo */
+.highlight .vc { color: #268BD2 } /* Name.Variable.Class */
+.highlight .vg { color: #268BD2 } /* Name.Variable.Global */
+.highlight .vi { color: #268BD2 } /* Name.Variable.Instance */
+.highlight .il { color: #2AA198 } /* Literal.Number.Integer.Long */
diff --git a/src/doc/woffify.rb b/src/doc/woffify.rb
new file mode 100644 (file)
index 0000000..33c9076
--- /dev/null
@@ -0,0 +1,9 @@
+require "fileutils"
+
+FileUtils.rm Dir["source/fonts/**/*.woff"]
+
+Dir["source/fonts/**/*.ttf"].each do |file|
+  out = file.sub(/\.ttf$/, ".woff").gsub(' ', "-")
+  puts "Converting `#{file}` to `#{out}`"
+  `~/npm/bin/ttf2woff "#{file}" "#{out}"`
+end